---
title: API des services d'images
i18nReady: true
---
import Since from '~/components/Since.astro';

`astro:assets` a été conçu pour permettre à tout service d'optimisation d'images de créer facilement un service reposant sur Astro.

## Qu'est-ce qu'un service d'images ?

Astro propose deux types de services d'images : Local et Externe.

- **Les services locaux** gèrent les transformations d'image directement lors de la compilation pour les sites statiques, ou lors de l'exécution, à la fois en mode développement et pour le rendu à la demande. Il s'agit souvent d'enveloppes autour de bibliothèques telles que Sharp, ImageMagick ou Squoosh. En mode développement et pour les routes en production rendues à la demande, les services locaux utilisent un point de terminaison d'API pour effectuer la transformation.
- Les **services externes** pointent vers des URL et peuvent ajouter la prise en charge de services tels que Cloudinary, Vercel ou tout autre serveur compatible avec [RIAPI](https://github.com/riapi/riapi).

## Construire à l'aide de l'API des services d'images

Les définitions de service prennent la forme d'un objet par défaut exporté avec diverses méthodes requises (« hooks »).

Les services externes fournissent une méthode `getURL()` qui pointe vers la `src` de la balise `<img>` après compilation.

Les services locaux fournissent une méthode `transform()` pour effectuer des transformations sur votre image, et les méthodes `getURL()` et `parseURL()` pour utiliser un point de terminaison pour le mode dev et lors du rendu à la demande.

Les deux types de services peuvent fournir `getHTMLAttributes()` pour déterminer les autres attributs de la sortie `<img>` et `validateOptions()` pour valider et augmenter les options transmises.

### Services externes

Un service externe pointe vers une URL distante à utiliser comme attribut `src` de la balise `<img>` finale. Cette URL distante est responsable du téléchargement, de la transformation et du renvoi de l'image.

```ts
import type { ExternalImageService, ImageTransform, AstroConfig } from "astro";

const service: ExternalImageService = {
  validateOptions(options: ImageTransform, imageConfig: AstroConfig['image']) {
    const serviceConfig = imageConfig.service.config;

    // Appliquer la largeur maximale définie par l'utilisateur.
    if (options.width && options.width > serviceConfig.maxWidth) {
      console.warn(`La largeur de l'image ${options.width} dépasse la largeur maximale ${serviceConfig.maxWidth}. Repli sur la largeur maximale.`);
      options.width = serviceConfig.maxWidth;
    }

    return options;
  },
  getURL(options, imageConfig) {
    return `https://monsupercdn.com/${options.src}?q=${options.quality}&w=${options.width}&h=${options.height}`;
  },
  getHTMLAttributes(options, imageConfig) {
    const { src, format, quality, ...attributes } = options;
		return {
			...attributes,
			loading: options.loading ?? 'lazy',
			decoding: options.decoding ?? 'async',
		};
	}
};


export default service;
```

### Services locaux

Pour créer votre propre service local, vous pouvez pointer vers le [point de terminaison intégré](https://github.com/withastro/astro/blob/main/packages/astro/src/assets/endpoint/generic.ts) (`/_image`), ou vous pouvez également créer votre propre point de terminaison qui peut appeler les méthodes du service.

```ts
import type { ImageTransform, LocalImageService, AstroConfig } from "astro";

const service: LocalImageService<AstroConfig["image"]> = {
  getURL(options: ImageTransform, imageConfig) {
    const searchParams = new URLSearchParams();
		searchParams.append('href', typeof options.src === "string" ? options.src : options.src.src);
		options.width && searchParams.append('w', options.width.toString());
		options.height && searchParams.append('h', options.height.toString());
		options.quality && searchParams.append('q', options.quality.toString());
		options.format && searchParams.append('f', options.format);
    return `/mon_point_de_terminaison_personnalise_qui_transforme_les_images?${searchParams}`;
    // Ou utilisez le point de terminaison intégré, qui appellera vos fonctions parseURL et transform :
    // return `/_image?${searchParams}`;
  },
  parseURL(url: URL, imageConfig) {
    const params = url.searchParams;
    return {
      src: params.get('href')!,
      width: params.has('w') ? parseInt(params.get('w')!) : undefined,
      height: params.has('h') ? parseInt(params.get('h')!) : undefined,
			format: params.get('f'),
      quality: params.get('q'),
    };
  },
  async transform(inputBuffer: Uint8Array, options: { src: string, [key: string]: any }, imageConfig) {
    const { buffer } = await mySuperLibraryThatEncodesImages(options);
    return {
      data: buffer,
      format: options.format,
    };
  },
  getHTMLAttributes(options, imageConfig) {
		let targetWidth = options.width;
		let targetHeight = options.height;
		if (typeof options.src === "object") {
			const aspectRatio = options.src.width / options.src.height;

			if (targetHeight && !targetWidth) {
				targetWidth = Math.round(targetHeight * aspectRatio);
			} else if (targetWidth && !targetHeight) {
				targetHeight = Math.round(targetWidth / aspectRatio);
			}
		}

		const { src, width, height, format, quality, ...attributes } = options;

		return {
			...attributes,
			width: targetWidth,
			height: targetHeight,
			loading: attributes.loading ?? 'lazy',
			decoding: attributes.decoding ?? 'async',
		};
	},
  propertiesToHash: ['src', 'width', 'height', 'format', 'quality'], 
};
export default service;
```

Au moment de la compilation des sites statiques et des routes pré-rendues, `<Image />` et `getImage(options)` appellent la fonction `transform()`. Ces derniers transmettent des options soit par les attributs du composant, soit par un argument `options`, respectivement. Les images transformées seront générées dans un dossier `dist/_astro`. Leurs noms de fichier contiendront un hachage des propriétés transmises à `propertiesToHash`. Cette propriété est optionnelle et sera définie par défaut sur `['src', 'width', 'height', 'format', 'quality']`. Si votre service d'images personnalisé dispose d’autres options qui modifient les images générées, ajoutez-les au tableau.

En mode développement et lors de l'utilisation d'un adaptateur pour effectuer le rendu à la demande, Astro ne sait pas à l'avance quelles images doivent être optimisées. Astro utilise un point de terminaison GET (par défaut, `/_image`) pour traiter les images au moment de l'exécution. `<Image />` et `getImage()` transmettent leurs options à `getURL()`, qui renvoie l'URL du point de terminaison. Ensuite, le point de terminaison appelle `parseURL()` et transmet les propriétés résultantes à `transform()`.

#### getConfiguredImageService & imageConfig

Si vous implémentez votre propre point de terminaison en tant que point de terminaison Astro, vous pouvez utiliser `getConfiguredImageService` et `imageConfig` pour appeler les méthodes `parseURL` et `transform` de votre service et fournir la configuration de l'image.

Pour accéder à la configuration du service d'image ([`image.service.config`](/fr/reference/configuration-reference/#imageservice)), vous pouvez utiliser `imageConfig.service.config`.

```ts title="src/api/mon_point_de_terminaison_personnalise_qui_transforme_les_images.ts"
import type { APIRoute } from "astro";
import { getConfiguredImageService, imageConfig } from 'astro:assets';

export const GET: APIRoute = async ({ request }) => {
  const imageService = await getConfiguredImageService();

  const imageTransform = imageService.parseURL(new URL(request.url), imageConfig);
  // ... récupère l'image à partir de imageTransform.src et la stocke dans inputBuffer
  const { data, format } = await imageService.transform(inputBuffer, imageTransform, imageConfig);
  return new Response(data, {
			status: 200,
			headers: {
				'Content-Type': mime.getType(format) || ''
      }
    }
  );
}
```

[Voir le point de terminaison intégré](https://github.com/withastro/astro/blob/main/packages/astro/src/assets/endpoint/generic.ts) pour un exemple complet.


## Hooks

### `getURL()`

<p>

**Type :** `(options: ImageTransform, imageConfig: AstroConfig['image']) => string | Promise<string>`<br />
<Since v="2.1.0" />
</p>

**Requis pour les services locaux et externes**

Pour les services locaux, ce hook renvoie l'URL du point de terminaison qui génère votre image (pour le rendu à la demande et en mode dev). Il n'est pas utilisé pendant la compilation. Le point de terminaison local vers lequel `getURL()` pointe peut appeler à la fois `parseURL()` et `transform()`.

Pour les services externes, ce hook renvoie l'URL finale de l'image.

Pour les deux types de services, les `options` sont les propriétés passées par l'utilisateur comme attributs du composant `<Image />` ou comme options de `getImage()`. Elles sont du type suivant :

```ts
export type ImageTransform = {
    // Images importées par l'ESM | chemins d'accès aux images distantes/publiques
    src: ImageMetadata | string;
    width?: number | undefined;
    height?: number | undefined;
    widths?: number[] | undefined;
	  densities?: (number | `${number}x`)[] | undefined;
    quality?: ImageQuality  | undefined;
    format?: OutputFormat | undefined;
    fit?: ImageFit | undefined;
    position?: string | undefined;
    [key: string]: any;
};
```


### `parseURL()`

<p>

**Type :** `(url: URL, imageConfig: AstroConfig['image']) => { src: string, [key: string]: any } | undefined | Promise<{ src: string, [key: string]: any }> | Promise<undefined>`<br />
<Since v="2.1.0" />
</p>

**Requis pour les services locaux uniquement ; indisponible pour les services externes**

Ce hook analyse les URLs générées par `getURL()` en un objet avec les différentes propriétés à utiliser par `transform` (en SSR et en mode dev). Il n'est pas utilisé pendant la compilation.

### `transform()`

<p>

**Type :** `(inputBuffer: Uint8Array, options: { src: string, [key: string]: any }, imageConfig: AstroConfig['image']) => Promise<{ data: Uint8Array; format: ImageOutputFormat }>`<br />
<Since v="2.1.0" />
</p>

**Requis pour les services locaux uniquement ; indisponible pour les services externes**

Ce hook transforme et renvoie l'image et est appelé pendant la compilation pour créer les fichiers de ressources finaux.

Vous devez renvoyer un `format` pour garantir que le type MIME approprié est fourni aux utilisateurs pour le rendu à la demande et le mode de développement.

### `getHTMLAttributes()`

<p>

**Type :** `(options: ImageTransform, imageConfig: AstroConfig['image'] ) => Record<string, any> | Promise<Record<string, any>>`<br />
<Since v="2.1.0" />
</p>

**Facultatif pour les services locaux et externes**

Ce hook renvoie tous les attributs supplémentaires utilisés pour restituer l'image en HTML, en fonction des paramètres transmis par l'utilisateur (`options`).

### `getSrcSet()`

<p>

**Type :** `(options: ImageTransform, imageConfig: AstroConfig['image'] ) => UnresolvedSrcSetValue[] | Promise<UnresolvedSrcSetValue[]>`<br />
<Since v="3.3.0" />
</p>

**Facultatif pour les services locaux et externes**

Ce hook génère plusieurs variantes de l'image spécifiée, par exemple, pour générer un attribut `srcset` sur une `<img>` ou `source` sur `<picture>`.

Ce hook retourne un tableau d'objets avec les propriétés suivantes :

```ts
export type UnresolvedSrcSetValue = {
	transform: ImageTransform;
	descriptor?: string;
	attributes?: Record<string, any>;
};
```

### `validateOptions()`

<p>

**Type :** `(options: ImageTransform, imageConfig: AstroConfig['image'] ) => ImageTransform | Promise<ImageTransform>`
<Since v="2.1.4" />
</p>

**Facultatif pour les services locaux et externes**

Ce hook vous permet de valider et d'augmenter les options passées par l'utilisateur. C'est utile pour définir des options par défaut, ou pour indiquer à l'utilisateur qu'un paramètre est nécessaire.

[Voir comment `validateOptions()` est utilisé dans les services intégrés d'Astro](https://github.com/withastro/astro/blob/0ab6bad7dffd413c975ab00e545f8bc150f6a92f/packages/astro/src/assets/services/service.ts#L124).

## Configuration de l'utilisateur

Configurez le service d'image à utiliser dans `astro.config.mjs`. La configuration prend la forme suivante :

```js title="astro.config.mjs"
import { defineConfig } from "astro/config";

export default defineConfig({
  image: {
    service: {
      entrypoint: "votre-point-d-entrée", // 'astro/assets/services/sharp' | string,
      config: {
        // ... configuration spécifique au service. En option.
      }
    }
  },
});
```

## Utilitaires

Astro propose plusieurs fonctions d'assistance permettant de développer un service d'images personnalisé. Ces utilitaires peuvent être importés depuis `astro/assets/utils` :

```ts
import { 
    isRemoteAllowed,
    matchHostname,
    matchPathname,
    matchPattern,
    matchPort,
    matchProtocol,
    isESMImportedImage,
    isRemoteImage,
    resolveSrc,
    imageMetadata,
    emitESMImage,
    emitImageMetadata,
    getOrigQueryParams,
    inferRemoteSize,
    propsToFilename,
    hashTransform
} from "astro/assets/utils";
```

### `isRemoteAllowed()`

<p>
**Type :** `(src: string, { domains, remotePatterns }: {domains: string[], remotePatterns: RemotePattern[] }) => boolean`<br />
<Since v="4.0.0" />
</p>

Détermine si une ressource distante donnée, identifiée par son URL source, est autorisée en fonction de domaines spécifiés et de modèles distants.


```ts
import { isRemoteAllowed } from 'astro/assets/utils';

const testImageURL = 'https://example.com/images/test.jpg';
const domains = ['example.com', 'anotherdomain.com'];
const remotePatterns = [
  { protocol: 'https', hostname: 'images.example.com', pathname: '/**' }, // Autoriser n'importe quel chemin sous ce nom d'hôte
];

const url = new URL(testImageURL);
const isAllowed = isRemoteAllowed(url.href, { domains, remotePatterns });

console.log(`L'image distante est-elle autorisée ? ${isAllowed}`);
```

### `matchHostname()`

<p>
**Type :** `(url: URL, hostname?: string, allowWildcard = false) => boolean`<br />
<Since v="4.0.0" />
</p>

Fait correspondre le nom d'hôte d'une URL donnée à un nom d'hôte spécifié, avec prise en charge facultative des modèles génériques.

```ts
import { matchHostname } from 'astro/assets/utils';

const testURL = new URL('https://sub.example.com/path/to/resource');

// Exemple d'utilisation de matchHostname
const hostnameToMatch = 'example.com';

// Correspondance sans caractère générique
const isMatchWithoutWildcard = matchHostname(testURL, hostnameToMatch);
console.log(`Le nom d'hôte correspond-il sans caractère générique ? ${isMatchWithoutWildcard}`); // Sortie : false

// Correspondance avec un caractère générique
const isMatchWithWildcard = matchHostname(testURL, hostnameToMatch, true);
console.log(`Le nom d'hôte correspond-il avec un caractère générique ? ${isMatchWithWildcard}`); // Sortie : true
```

### `matchPathname()`

<p>
**Type :** `(url: URL, pathname?: string, allowWildcard = false) => boolean`<br />
<Since v="4.0.0" />
</p>

Fait correspondre le chemin d'accès d'une URL donnée à un modèle spécifié, avec prise en charge facultative des caractères génériques.

```ts
import { matchPathname } from 'astro/assets/utils';

const testURL = new URL('https://example.com/images/photo.jpg');

// Exemple de chemin d'accès à faire correspondre
const pathnameToMatch = '/images/photo.jpg';

// Correspondance sans caractère générique
const isMatchWithoutWildcard = matchPathname(testURL, pathnameToMatch);
console.log(`Le nom du chemin correspond-il sans caractère générique ? ${isMatchWithoutWildcard}`); // Sortie : true

// Correspondance avec un caractère générique
const wildcardPathname = '/images/*';
const isMatchWithWildcard = matchPathname(testURL, wildcardPathname, true);
console.log(`Le nom du chemin correspond-il avec un caractère générique ? ${isMatchWithWildcard}`); // Sortie : true
```

### `matchPattern()`

<p>
**Type :** `(url: URL, remotePattern: RemotePattern) => boolean`<br />
<Since v="4.0.0" />
</p>

Évalue si une URL donnée correspond au modèle distant spécifié en fonction du protocole, du nom d'hôte, du port et du chemin d'accès.

```ts
import { matchPattern } from 'astro/assets/utils';

const testURL = new URL('https://images.example.com/photos/test.jpg');

// Définir un modèle distant pour correspondre à l'URL
const remotePattern = {
  protocol: 'https',
  hostname: 'images.example.com',
  pathname: '/photos/**', // Caractère générique pour autoriser tous les fichiers sous /photos/
  port: '', // Facultatif : faites correspondre n'importe quel port ou laissez vide par défaut
};

// Vérifiez si l'URL correspond au modèle distant
const isPatternMatched = matchPattern(testURL, remotePattern);

console.log(`L'URL correspond-elle au modèle distant ? ${isPatternMatched}`); // Sortie : true
```

### `matchPort()`

<p>
**Type :** `(url: URL, port?: string) => boolean`<br />
<Since v="4.0.0" />
</p>

Vérifie si le port de l'URL donnée correspond au port spécifié. Si aucun port n'est fourni, renvoie `true`.

```ts
import { matchPort } from 'astro/assets/utils';

const testURL1 = new URL('https://example.com:8080/resource');
const testURL2 = new URL('https://example.com/resource');

// Exemple d'utilisation de matchPort
const portToMatch = '8080';

// Faire correspondre une URL avec un port spécifié
const isPortMatch1 = matchPort(testURL1, portToMatch);
console.log(`Le port correspond-il ? ${isPortMatch1}`); // Sortie : true

// Faire correspondre une URL sans port spécifié (le port par défaut sera supposé)
const isPortMatch2 = matchPort(testURL2, portToMatch);
console.log(`Le port correspond-il ? ${isPortMatch2}`); // Sortie : false

// Vérifier une URL sans fournir explicitement de port (la valeur par défaut est true si le port n'est pas défini)
const isPortMatch3 = matchPort(testURL1);
console.log(`Le port correspond-il (aucun port spécifié) ? ${isPortMatch3}`); // Sortie : true
```

### `matchProtocol()`

<p>
**Type :** `(url: URL, protocol?: string) => boolean`<br />
<Since v="4.0.0" />
</p>

Compare le protocole de l'URL fournie avec un protocole spécifié.

```ts
import { matchProtocol } from 'astro/assets/utils';

const testURL1 = new URL('https://example.com/resource');
const testURL2 = new URL('http://example.com/resource');

// Exemple d'utilisation de matchProtocol
const protocolToMatch = 'https';

// Faire correspondre une URL avec le bon protocole
const isProtocolMatch1 = matchProtocol(testURL1, protocolToMatch);
console.log(`Le protocole correspond-il pour testURL1 ? ${isProtocolMatch1}`); // Sortie : true

// Faire correspondre une URL avec un protocole incorrect
const isProtocolMatch2 = matchProtocol(testURL2, protocolToMatch);
console.log(`Le protocole correspond-il pour testURL2? ${isProtocolMatch2}`); // Sortie : false

// Faire correspondre une URL sans fournir explicitement de protocole (la valeur par défaut est true si le protocole n'est pas défini)
const isProtocolMatch3 = matchProtocol(testURL1);
console.log(`Le protocole correspond-il (aucun protocole spécifié) ? ${isProtocolMatch3}`); // Sortie : true
```

### `isESMImportedImage()`

<p>
  **Type :** `(src: ImageMetadata | string) => boolean`<br />
  <Since v="4.0.0" />
</p>

Détermine si la source donnée est une image importée en tant que module ECMAScript (ESM).

```ts
import { isESMImportedImage } from 'astro/assets/utils';

// Exemple d'utilisation de isESMImportedImage
const imageMetadataExample = {
  src: '/images/photo.jpg',
  width: 800,
  height: 600,
  format: 'jpg',
};

const filePathExample = '/images/photo.jpg';

// Vérifiez si l'entrée est une image importée ESM
const isMetadataImage = isESMImportedImage(imageMetadataExample);
console.log(`Est-ce que imageMetadataExample est une image importée ESM ? ${isMetadataImage}`); // Résultat : true

const isFilePathImage = isESMImportedImage(filePathExample);
console.log(`filePathExample est-il une image importée ESM ? ${isFilePathImage}`); // Résultat : false
```


### `isRemoteImage()`

<p>
  **Type :** `(src: ImageMetadata | string) => boolean`<br />
  <Since v="4.0.0" />
</p>

Détermine si la source fournie est une URL d'image distante sous la forme d'une chaîne de caractères.


```ts
import { isRemoteImage } from 'astro/assets/utils';

// Exemple d'utilisation de isRemoteImage
const remoteImageUrl = 'https://example.com/images/photo.jpg';
const localImageMetadata = {
  src: '/images/photo.jpg',
  width: 800,
  height: 600,
  format: 'jpg',
};

// Vérifiez si l'entrée est une URL d'image distante
const isRemote1 = isRemoteImage(remoteImageUrl);
console.log(`remoteImageUrl est-elle une image distante ? ${isRemote1}`); // Résultat : true

const isRemote2 = isRemoteImage(localImageMetadata);
console.log(`localImageMetadata est-elle une image distante ? ${isRemote2}`); // Résultat : false
```

### `resolveSrc()`

<p>
  **Type :** `(src: UnresolvedImageTransform['src']) => Promise<string | ImageMetadata>`<br />
  <Since v="4.0.0" />
</p>

Renvoie la source de l'image. Cette fonction garantit que si `src` est une promesse (par exemple, une importation dynamique (`import()`)), elle est attendue et la bonne `src` est extraite. Si `src` est déjà une valeur résolue, elle est renvoyée telle quelle.

```ts
import { resolveSrc } from 'astro/assets/utils';
import imageLocale from "./images/photo.jpg";

const resolvedLocal = await resolveSrc(imageLocale);
// sera `{ src: '/images/photo.jpg', width: 800, height: 600, format: 'jpg' }`

const resolvedRemote = await resolveSrc("https://example.com/img-distante.jpg");
// sera `"https://example.com/img-distante.jpg"`

const resolvedDynamic = await resolveSrc(import("./images/image-dynamique.jpg"))
// sera `{ src: '/images/image-dynamique.jpg', width: 800, height: 600, format: 'jpg' }`
```


### `imageMetadata()`

<p>
  **Type :** `(data: Uint8Array, src?: string) => Promise<Omit<ImageMetadata, 'src' | 'fsPath'>>`<br />
  <Since v="4.0.0" />
</p>

Extrait les métadonnées de l'image telles que les dimensions, le format et l'orientation des données d'image fournies.

```ts
import { imageMetadata } from 'astro/assets/utils';

async function extractImageMetadata() {
  // Exemple de données d'image (Uint8Array)
  const exampleImageData = new Uint8Array([/* ...données d'image binaires... */]);

  // Chemin source facultatif (utile pour le débogage ou le contexte de métadonnées supplémentaires)
  const sourcePath = '/images/photo.jpg';

  try {
    // Extraire les métadonnées des données d'image
    const metadata = await imageMetadata(exampleImageData, sourcePath);

    console.log("Métadonnées d'image extraites :", metadata);
    // Exemple de sortie :
    // {
    //   width: 800,
    //   height: 600,
    //   format: 'jpg',
    //   orientation: undefined
    // }
  } catch (error) {
    console.error("Échec de l'extraction des métadonnées de l'image :", error);
  }
}

await extractImageMetadata();
```

### `emitESMImage()`

:::caution[Dépréciée]
Utilisez plutôt la fonction [`emitImageMetadata`](#emitimagemetadata).
:::

<p>
  **Type :** `(id: string | undefined, _watchMode: boolean, experimentalSvgEnabled: boolean,  fileEmitter?: FileEmitter) => Promise<ImageMetadataWithContents | undefined>`<br />
  <Since v="4.0.0" />
</p>


Traite un fichier image et émet ses métadonnées et éventuellement son contenu. En mode compilation, la fonction utilise `fileEmitter` pour générer une référence de ressource. En mode développement, elle résout l'URL d'un fichier local avec des paramètres de requête pour les métadonnées.

```ts

import { emitESMImage } from 'astro/assets/utils';

const imageId = '/images/photo.jpg';
const unusedWatchMode = false; // Dépréciée, inutilisé
const unusedExperimentalSvgEnabled = false; // Définissez sur `true` uniquement si vous utilisez SVG et souhaitez que les données du fichier soient intégrées

try {
  const result = await emitESMImage(imageId, unusedWatchMode, unusedExperimentalSvgEnabled);
  if (result) {
    console.log("Métadonnées d'image avec contenu :", result);
    // Exemple de sortie :
    // {
    //   width: 800,
    //   height: 600,
    //   format: 'jpg',
    //   contents: Uint8Array([...])
    // }
  } else {
    console.log("Aucune métadonnée n'a été émise pour cette image.");
  }
} catch (error) {
  console.error("Échec de l'émission de l'image ESM :", error);
}

```

### `emitImageMetadata()`

<p>
  **Type :** `(id: string | undefined, fileEmitter?: FileEmitter) => Promise<ImageMetadataWithContents | undefined>`<br />
  <Since v="5.7.0" />
</p>


Traite un fichier image et émet ses métadonnées et éventuellement son contenu. En mode compilation, la fonction utilise `fileEmitter` pour générer une référence de ressource. En mode développement, elle résout l'URL d'un fichier local avec des paramètres de requête pour les métadonnées.

```ts

import { emitImageMetadata } from 'astro/assets/utils';

const imageId = '/images/photo.jpg';

try {
  const result = await emitImageMetadata(imageId);
  if (result) {
    console.log("Métadonnées d'image avec contenu :", result);
    // Exemple de sortie :
    // {
    //   width: 800,
    //   height: 600,
    //   format: 'jpg',
    //   contents: Uint8Array([...])
    // }
  } else {
    console.log("Aucune métadonnée n'a été émise pour cette image.");
  }
} catch (error) {
  console.error("Échec de l'émission de l'image ESM :", error);
}

```

### `getOrigQueryParams()`

<p>
  **Type :** `(params: URLSearchParams) => Pick<ImageMetadata, 'width' | 'height' | 'format'> | undefined`<br />
  <Since v="4.0.0" />
</p>


Récupère la largeur (`width`), la hauteur (`height`) et le `format` d'une image à partir d'un objet [`URLSearchParams`](https://developer.mozilla.org/fr/docs/Web/API/URLSearchParams). Si l'un de ces paramètres est manquant ou non valide, la fonction renvoie `undefined`.

```ts

import { getOrigQueryParams } from 'astro/assets/utils';

const url = new URL('https://example.com/image.jpg?width=800&height=600&format=jpg');
const queryParams = url.searchParams;

// Extraire les paramètres de requête d'origine
const origParams = getOrigQueryParams(queryParams);

if (origParams) {
  console.log("Paramètres de requête d'origine :", origParams);
  // Exemple de sortie :
  // {
  //   width: 800,
  //   height: 600,
  //   format: 'jpg'
  // }
} else {
  console.log("Échec de l'extraction des paramètres de requête d'origine.");
}
```

### `inferRemoteSize()`

<p>
  **Type :** `(url: string) => Promise<Omit<ImageMetadata, 'src' | 'fsPath'>>`<br />
  <Since v="4.0.0" />
</p>

Déduit les dimensions d'une image distante en diffusant ses données et en les analysant progressivement jusqu'à ce que suffisamment de métadonnées soient disponibles.

```ts

import { inferRemoteSize } from 'astro/assets/utils';

async function getRemoteImageSize() {
  const remoteImageUrl = 'https://example.com/image.jpg';

  try {
    // Déduire la taille de l'image distante à partir de l'URL
    const imageSize = await inferRemoteSize(remoteImageUrl);

    console.log("Taille de l'image distante déduite :", imageSize);
    // Exemple de sortie :
    // {
    //   width: 1920,
    //   height: 1080,
    //   format: 'jpg'
    // }
  } catch (error) {
    console.error("Impossible de déduire la taille de l'image distante :", error);
  }
}

await getRemoteImageSize();
```

### `propsToFilename()`

<p>
  **Type :** `(filePath: string, transform: ImageTransform, hash: string) => string`<br />
  <Since v="4.0.0" />
</p>


Génère un nom de fichier formaté pour une image en fonction de son chemin source, de ses propriétés de transformation et d'un hachage unique.

Le nom de fichier formaté suit cette structure :

`<prefixDirname>/<baseFilename>_<hash><outputExtension>`

- `prefixDirname` : Si l'image est une image importée ESM, il s'agit du nom du répertoire du chemin du fichier d'origine ; sinon, ce sera une chaîne de caractères vide.
- `baseFilename` : Le nom de base du fichier ou un nom court haché si le fichier est un URI `data:`.
- `hash` : Une chaîne de hachage unique générée pour distinguer le fichier transformé.
- `outputExtension` : L'extension du fichier de sortie souhaitée dérivée de `transform.format` ou de l'extension du fichier d'origine.

```ts
import { propsToFilename } from 'astro/assets/utils';

function generateTransformedFilename() {
  const filePath = '/images/photo.jpg';
  const transform = {
    format: 'png',
    src: '/images/photo.jpg'
  };
  const hash = 'abcd1234';

  // Générer le nom de fichier transformé en fonction du chemin du fichier, de la transformation et du hachage
  const filename = propsToFilename(filePath, transform, hash);

  console.log('Nom de fichier transformé généré :', filename);
  // Exemple de sortie : '/images/photo_abcd1234.png'
}

generateTransformedFilename();
```

### `hashTransform()`

<p>
  **Type :** `(transform: ImageTransform, imageService: string, propertiesToHash: string[]) => string`<br />
  <Since v="4.0.0" />
</p>

Transforme l'objet `transform` fourni en une chaîne de hachage basée sur les propriétés sélectionnées et le `imageService` spécifié.

```ts

import { hashTransform } from 'astro/assets/utils';

function generateTransformHash() {
  const transform = {
    src: '/images/photo.jpg',
    width: 800,
    height: 600,
    format: 'jpg',
  };

  const imageService = 'astroImageService';
  const propertiesToHash = ['width', 'height', 'format'];

  // Générer le hachage en fonction de la transformation, du service d'image et des propriétés
  const hash = hashTransform(transform, imageService, propertiesToHash);

  console.log('Hachage de transformation généré :', hash);
  // Exemple de sortie : 'd41d8cd98f00b204e9800998ecf8427e'
}

generateTransformHash();
```
